Set Up and Configuration for Reporting and Metrics Agent

The Reporting and Metrics Agent is a Windows service that securely communicates with the Knowledge Tier. For technical details, including ports and domains that may be needed for firewall rules, refer to the Knowledge Tier Agent Connection URLS documentation.

NOTE: Outgoing firewall policies must allow the service to initiate a connection to onprem.syniti.com:443.

NOTE: To install and configure the Reporting and Metrics Agent, you must have administrative rights on the server where the Reporting and Metrics Agent will be installed.

NOTE:Please open a Support ticket for assistance in presenting Stewardship Tier data in your custom dashboards.

Prerequisites

  • Stewardship Tier 7.2.0 or later must be installed.
  • Outbound traffic the following domain must be permitted so that the Reporting and Metrics Agent can communicate with the cloud:

    • onprem.syniti.com:443

    • agent.virtyx.com:443

    • realtime.virtyx.com:443

NOTE: The standard deployment configuration requires the Reporting and Metrics Agent to be installed on the same server as Stewardship Tier. For alternative configurations please contact Syniti Support for assistance.

System Requirements for the Reporting and Metrics Agent

  • Windows Server 2019
  • Windows Server 2016

Set up the Reporting and Metrics Agent

The Reporting and Metrics Agent transfers reporting-relevant data from the Stewardship Tier to the Knowledge Tier. This agent is installed with the Stewardship Tier, which allows the dashboard to be accessed through the Knowledge Tier.

To set up the Reporting and Metrics Agent:

Create a SQL Server Login for the Reporting and Metrics Agent Service

The Reporting and Metrics Agent can use the same SQL Server login that was created for the Stewardship Tier installation without needing any security or role access changes for that login. However, it is recommended to create a different login for the Reporting and Metrics Agent with limited access. This login is created after the new Stewardship Tier installation or Stewardship Tier upgrade has been completed.

To create a SQL Server login with the limited access rights needed for the Reporting and Metrics Agent:

  1. Open SQL Server Management Studio.
  2. Log in with a user that has permissions to create a new login.
  3. Connect Object Explorer to the appropriate SQL Server instance.
  4. Expand the Security folder.
  5. Right-click Logins.
  6. Select New Login from the menu.

  7. Name the login (for example, metricagent).

    NOTE: Do not use periods (.) in the login name.

  8. Select SQL Server Authentication.
  9. Enter a password in the Password field.
  10. Re-enter password in the Confirm Password field.

  11. Uncheck the Enforce Password Policy check box.

    NOTE: Disabling Enforce Password Policy prevents the password from expiring. An expired password causes the Reporting and Metrics Agent to become periodically unavailable.

  12. Change the Default Database for the user to “Console.”
  13. Click the OK button to create the login.

Configure Rights for the Reporting and Metrics Agent Login

Configure Access for the Login Created for the Reporting and Metrics Agent Service

To configure access for the login created for the Reporting and Metrics Agent service:

  1. Open SQL Server Management Studio.
  2. Log in with a user that has permissions to create a new login.
  3. Connect Object Explorer to the appropriate SQL Server instance.
  4. Expand the Logins branch of the Security folder.
  5. Right-click the Metrics Agent Login in the expanded list.
  6. Click Properties; the Login Properties panel opens.
  7. Click User Mapping in the Select a page vertical menu.

  8. Click the cMap check box under the Users mapped to this login panel.

    NOTE: Verify that cMap is selected before setting database role memberships.

  9. While cMap is selected in the Users mapped to this login panel, locate the Database role membership for: cMap section and click the check box for the db_datareader role.

  10. Click the Console check box under the Users mapped to this login panel.

    NOTE: Verify that Console is selected before setting database role memberships.

  11. While Console is selected in the Users mapped to this login panel, locate the Database role membership for: cMap panel and click the check box for the db_datareader role.

  12. Click the CranSoft check box under the Users mapped to this login panel.

  13. Click the DSPCommon check box under the Users mapped to this login panel.

    NOTE: CranSoft and DSPCommon are given limited access to a few specific SQL objects. Therefore, these databases do not need access to the db_datareader role.

  14. Click the DSW check box under the Users mapped to this login panel.

    NOTE: Verify that DSW is selected before setting database role memberships.

  15. While DSW is selected in the Users mapped to this login panel, locate the Database role membership for: cMap panel and click the check box for the db_datareader role.

  16. Click OK; the Login Properties panel closes.

Configure Access to Schemas and Objects Under the CranSoft Database

To configure access to schemas and objects under the CranSoft database:

  1. Open SQL Server Management Studio.
  2. Log in with a user that has permissions to create a new login.
  3. Connect Object Explorer to the appropriate SQL Server instance.
  4. Expand Databases, then expand the CranSoft database.
  5. In the expanded CranSoft database list, expand Security and then Users.
  6. In the expanded Users list, find the Reporting and Metrics Agent user that was created in the Create a SQL Server Login for the Reporting and Metrics Agent Service section.
  7. Right-click the user and select Properties; the Database user panel opens.
  8. In the Select a page vertical menu, click Securables.

  9. Click the Search… button; the Add Objects window opens.

  10. Select Specific Objects and click OK; the Select Objects window opens.

  11. Click the Object Types… button; the Select Object Types window opens.

  12. Click the check box to select Tables.

  13. Click OK; the Select Object Types window closes.

  14. On the Select Objects window. in the Enter Object Names to Select section, enter this text:

    [dbo].[DataSource]; [dbo].[User];[dbo].[WebApp]

  15. Click OK; the Select Objects window closes.

  16. On the Database User window in the Securables section, select DataSource.

  17. In the Permissions for dbo.Datasource section on the Explicit tab, click the Grant check box for the Select permission.

  18. Click the Column Permissions button; the Column Permissions window opens.

  19. Find the column "Database" and click the Grant check box.

  20. Find the column "DataSourceID" and select Grant.

  21. Click OK; the Column Permissions window closes.

  22. In the Securables section, select WebApp.

  23. In the Explicit section, find the Select permission and click Grant.

  24. Click the Column Permissions button; the Column Permissions window opens

  25. Find the column "WebAppID" and select Grant.

  26. Find the column "Version" and select Grant.

     

  27. In the Securables section, select User.

  28. In the Explicit section, find the Select permission and click Grant.

  29. Click the Column Permissions button; the Column Permissions window opens

  30. Find the column "Name" and select Grant.

  31. Find the column "UserID" and select Grant.

  1. Click OK; the Column Permissions window closes.

  2. Click OK; the Database User window closes.

Configure Access to Schemas and Objects Under the DSPCommon Database

To configure access to schemas and objects under the DSPCommon database:

  1. Open SQL Server Management Studio.
  2. Connect to the database server.
  3. Right click the DSPCommon database.
  4. Select New Query.
  5. Update the following SQL statement by changing “metricagent” with the login name created in the Create a SQL Server Login for the Reporting and Metrics Agent Service section and run the SQL statement in the New Query window running in the DSPCommon database:

GRANT EXECUTE ON SCHEMA::[dbo] TO [metricagent]

GO

Configure Access to Schemas and Objects Under the cMap Database

To configure access to schemas and objects under the cMap database:

  1. Open SQL Server Management Studio.
  2. Connect to the database server.
  3. Right click the cMap database.
  4. Select New Query.
  5. Update the following SQL statement by changing “metricagent” with the login name created in the Create a SQL Server Login for the Reporting and Metrics Agent Service section and run the SQL statement in the New Query window running in the cMap database:

GRANT EXECUTE ON SCHEMA::[dbo] TO [metricagent]

GO

Configure Access to Schemas and Objects Under the Console Database

To configure access to schemas and objects under the Console database:

  1. Open SQL Server Management Studio.
  2. Connect to the database server.
  3. Right click the Console database.
  4. Select New Query.
  5. Update the following SQL statement by changing “metricagent” with the login name created in the Create a SQL Server Login for the Reporting and Metrics Agent Service section and run the SQL statement in the New Query window running in the Console database:

GRANT EXECUTE ON SCHEMA::[dbo] TO [metricagent]

GO

Link Stewardship Tier Instance to Knowledge Tier Tenant

To link the Stewardship Tier instance to the Knowledge Tier tenant:

  1. Create the Knowledge Tier reporting site.
  2. Update the Reporting and Metric Agent configuration.
  3. Start the Reporting and Metric Agent service.

Create the Knowledge Tier Reporting Site

To create the Knowledge Tier reporting site:

  1. Click the Sites icon in the Guidance panel.

  2. Click the Add Site icon.

  3. Select Reporting and Metrics from the Purpose list box.

  4. Enter a name for the site in the Name field.

  5. Enter the login name created for the Reporting and Metrics Agent Service in the Username field.

  6. Enter the password of the login name created for the Reporting and Metrics Agent Service in the Password field.

  7. Enter the hostname or IP address of your server in the Hostname field.

  8. Enter the port for your server in the Port field (MS SQL Server default port is 1433).

  9. Enter the name of the database to which you want to connect in the Instance field. Leave this field blank if not applicable

    NOTE: The connection information is the same information that the Stewardship Tier WebApp is configured to use for connecting to the database. This address is relative to the Stewardship Tier WebApp server because in most cases, the Stewardship Tier database is only exposed to a local network. The address could be an internal hostname or an RFC 1918 address so long as the Stewardship Tier WebApp machine can resolve the name and connect to it.

    NOTE: The Stewardship Tier database may or may not be on the same machine as the Stewardship Tier WebApp, which is where the Reporting and Metrics Agent runs to collect the data.

    NOTE: Use the User name and Password created in the Create a SQL Server Login for the Reporting and Metrics Agent Service section. The Stewardship Tier database may or may not be on the same machine as the Stewardship Tier WebApp, which is where the Reporting and Metrics Agent runs to collect the data.

    NOTE: The Connection URL field automatically populates with the connection information you provide in the credentials fields. If you need to customize the URL or have been provided an agent connection URL by your database administrator, paste the URL directly into the Connection URL field. It’s important that the URL entered is encoded to ensure that unprintable characters or characters with special meaning are translated to values that are unambiguous and universally accepted by web browsers and servers.

    10. Copy and save the contents of the Config File Field to a text file.

    NOTE: The Config File will disappear once you navigate away from the page, so be sure to save it somewhere secure first.

    1. Click Save to save your connection and hide your credentials.

    NOTE: The contents of the Connection URL in the Config File are used to link the Stewardship Tier to the Knowledge Tier tenant.

Update the Reporting and Metric Agent Configuration

To update the Reporting and Metric Agent configuration:

  1. Copy the contents of the Config File field in the Knowledge Tier.
  2. Create a new text document and name it “config.json.” Make sure the file extension is “.json” and not “.txt.”
  3. Paste the text from the Config File field into the new config.json file.
  4. Move the config.json file to the C:\Windows\system32 \config\systemprofile\AppData\Virtyx\.virtyx folder on the Stewardship Tier application server. This folder was automatically created during the Stewardship Tier installation.

NOTE: This /.virtyx folder starts out empty. After starting the service, several .exe files are created in the folder automatically by the service.

Start the Reporting and Metrics Agent Windows Service and Confirm the Site's Status

The Reporting and Metrics Agent, which internally is called the “Virtyx Agent,” is installed with the Stewardship Tier. It will not be running upon installation; it needs the config.json file in order to start communicating with the Knowledge Tier. This service runs every 30 minutes.

Before the Reporting and Metrics Agent service can be started, the folder that contains the config.json file must be whitelisted.

NOTE: These steps may vary depending on the version of Windows.

To add the Reporting and Metrics Agent folder as an excluded folder:

  1. Copy the following folder path: C:\Windows\system32\config\systemprofile\AppData\Virtyx\.virtyx

  2. Open Windows Defender and select Settings.

    Or

  1. Select Start > Settings > Update & Security > Windows Security > Virus & threat protection in the Windows menu; the Windows Security menu opens. Under the Virus & threat protection settings heading, click the Manage settings link.
  2. Under the Exclusions heading, click the Add an exclusions link.
  3. Click Exclude a Folder.
  4. Paste the folder path into the search bar and click Enter to navigate to the folder.
  5. Click the Exclude this Folder button.

To start the Reporting and Metrics Agent windows service:

  1. Open Windows Start Menu.
  2. Perform a search on “Services” and open the Services application from the results.
  3. Locate Virtyx Agent in the Services application.
  4. Right-click Virtyx Agent.
  5. Select Start.

To confirm the site’s status, log in to the Knowledge Tier and confirm the site’s status is “Last Upload Successful.”

If this message does not display, consult the Troubleshooting documentation in the Knowledge Tier help.

If you click the … icon error messages returned from the agent in the last 48 hours display.